---
id: migration-v8
title: Migration Guide to v8
---

This guide explains the changes required to migrate from Orval v7 to v8.

## 1. Converted to ESM (ECMAScript Modules)

The project has been fully converted from CommonJS to ESM. This modernizes the codebase and aligns with the JavaScript ecosystem's direction.

### Key Changes

- All packages now use `"type": "module"` in package.json
- Import/export syntax instead of require()
- Node.js 22.18 or higher is required
- Configuration files should use `.mjs` extension or set `"type": "module"`
  - however, `.ts` is still the preferred format and requires no changes if written in `ESM` style

### How to migrate

#### Update Node.js version

Ensure you're using Node.js 22.18 or higher:

```bash
node --version  # Should be >= 22.18.0
```

#### Update configuration files

If you're using a JavaScript configuration file, either:

1. Rename it to use `.mjs` extension:

```bash
mv orval.config.js orval.config.mjs
```

2. Or add `"type": "module"` to your package.json:

```diff:package.json
{
  "name": "your-project",
+ "type": "module",
  ...
}
```

#### Update imports in your code

If you were importing Orval programmatically:

```diff:your-script.js
- const { generate } = require('orval');
+ import { generate } from 'orval';
```

#### Update dynamic imports

If you were using dynamic imports:

```diff:your-script.js
- const config = require('./orval.config.js');
+ const config = await import('./orval.config.js');
```

### Benefits of ESM

- **Better tree-shaking**: Unused code is more easily eliminated
- **Native browser support**: ESM works directly in modern browsers
- **Async module loading**: Improved performance with lazy loading
- **Future-proof**: Aligns with JavaScript ecosystem standards
- **Stricter module boundaries**: Better encapsulation and type safety

## 2. Changed default value of httpClient from `axios` to `fetch`

We changed the default httpClient from `axios` to `fetch` to reduce bundle size and eliminate the need for additional dependencies.

### How to maintain compatibility

If you want to keep using axios, configure it as follows:

```diff:orval.config.ts
export default {
  petstore: {
    output: {
+     httpClient: 'axios', // Explicitly specify
      target: './src/api',
    },
    input: {
      target: './petstore.yaml',
    },
  },
};
```

## 3. Removed `override.fetch.explode` option

This parameter was kept only for compatibility. Since compatibility maintenance is no longer needed in major versions, it has been removed.

### How to maintain compatibility

Specify `explode` directly in the OpenAPI specification file.

```diff:petstore.yaml
paths:
  /pets:
    get:
      parameters:
        - name: tags
          in: query
+         explode: true
          schema:
            type: array
```

## 4. Changed default value of `override.mock.delay` from `1000` to `false`

We disabled the default delay as it creates noise.

### How to maintain compatibility

If you want to explicitly set a delay, specify it in milliseconds.

```diff:orval.config.ts
export default {
  petstore: {
    output: {
      mock: {
+       delay: 1000, // In milliseconds
      },
    },
  },
};
```

## 5. Removed `override.coerceTypes`

This was removed as it has been replaced by the more flexible and explicit `override.zod.coerce`.

### How to maintain compatibility

Use `override.zod.coerce`.

```diff:orval.config.ts
export default {
  petstore: {
    output: {
      override: {
-       coerceTypes: true
+       zod: {
+         coerce: {
+           param: true,
+           query: true,
+           header: true,
+           body: true,
+           response: true
+         }
+       }
      },
    },
  },
};
```

## 6. Removed `override.useNativeEnums`

This was removed as it has been integrated into `enumGenerationType`.

### How to maintain compatibility

Use `enumGenerationType`.

```diff:orval.config.ts
export default {
  petstore: {
    output: {
      override: {
-       useNativeEnums: true
+       enumGenerationType: 'enum'
      },
    },
  },
};
```
